
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_Hans">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>API 的稳定性 &#8212; Django 3.2.6.dev 文档</title>
    <link rel="stylesheet" href="../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <link rel="index" title="索引" href="../genindex.html" />
    <link rel="search" title="搜索" href="../search.html" />
    <link rel="next" title="设计理念" href="design-philosophies.html" />
    <link rel="prev" title="元文件和杂记" href="index.html" />



 
<script src="../templatebuiltins.js"></script>
<script>
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../ref/templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);</script>

  </head><body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../index.html">Django 3.2.6.dev 文档</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../index.html">Home</a>  |
        <a title="Table of contents" href="../contents.html">Table of contents</a>  |
        <a title="Global index" href="../genindex.html">Index</a>  |
        <a title="Module index" href="../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="index.html" title="元文件和杂记">previous</a>
     |
    <a href="index.html" title="元文件和杂记" accesskey="U">up</a>
   |
    <a href="design-philosophies.html" title="设计理念">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="misc-api-stability">
            
  <div class="section" id="s-api-stability">
<span id="api-stability"></span><h1>API 的稳定性<a class="headerlink" href="#api-stability" title="永久链接至标题">¶</a></h1>
<p>Django 致力于 API 的稳定性和向前兼容性。简而言之，这意味着你在一个 Django 版本开发的代码可以继续在未来的版本中使用。在升级你的项目使用的 Django 版本时，你可能需要做一些小的更改: 了解你要升级的一个或多个版本请参阅 <a class="reference internal" href="../releases/index.html"><span class="doc">发行版注解</span></a> 中的“向后不兼容更改”部分。</p>
<p>在将 API 的稳定性作为一个非常重要的优先级的同时，Django 还致力于持续的改进，并致力于在我们提供的 API 中实现“一种方法”（最终）。这意味着，当我们发现明显更好的实现方式时，我们会弃用旧的方式，并最终将其移除。我们的目标是提供一个现代的、可靠的、高质量的 web 框架，帮助所有使用它的项目的使用最佳实践。通过使用渐进式的改进，我们试图避免停滞和大规模破坏性升级。</p>
<div class="section" id="s-what-stable-means">
<span id="what-stable-means"></span><h2>什么是“稳定”？<a class="headerlink" href="#what-stable-means" title="永久链接至标题">¶</a></h2>
<p>在此处，稳定意味着：</p>
<ul>
<li><p class="first">所有发布的 API （在文档中的一切 API ）在不提供向后兼容的别名的情况下，都不会被移除或者重命名。</p>
</li>
<li><p class="first">如果文档中的 API 添加了新特性（这是极有可能的），新特性不会导致现有方法罢工或者修改方法的含义。也就是说，“稳定性”并不意味着“不变性”。</p>
</li>
<li><p class="first">假如因为某些原因，一个“稳定的” API 必须被移除或者被代替，它将会被弃用但仍然会被保留直到至少有两个新特性发布。当调用即将被弃用的方法时，会产生警告。</p>
<p>有关 Django 是如何编写版本号以及一些功能是如何被弃用的详细信息，请看： <a class="reference internal" href="../internals/release-process.html#official-releases"><span class="std std-ref">正式发行</span></a>。</p>
</li>
<li><p class="first">如果一个 bug 或安全漏洞完全不可避免，我们才会直接打破这些 API 的向后兼容性而不走弃用过程。</p>
</li>
</ul>
</div>
<div class="section" id="s-stable-apis">
<span id="stable-apis"></span><h2>稳定的 API<a class="headerlink" href="#stable-apis" title="永久链接至标题">¶</a></h2>
<p>一般来说，文档中的一切都确定是稳定的，除开 <a class="reference internal" href="../internals/index.html"><span class="doc">内部区域</span></a>。</p>
</div>
<div class="section" id="s-exceptions">
<span id="exceptions"></span><h2>例外<a class="headerlink" href="#exceptions" title="永久链接至标题">¶</a></h2>
<p>这种稳定性和向后兼容性承诺有一些例外。</p>
<div class="section" id="s-security-fixes">
<span id="security-fixes"></span><h3>安全修复<a class="headerlink" href="#security-fixes" title="永久链接至标题">¶</a></h3>
<p>如果我们发现了安全问题 --希望报告者遵照我们的 <a class="reference internal" href="../internals/security.html#reporting-security-issues"><span class="std std-ref">安全报告政策</span></a>--我们会尽一切努力解决它。 这可能意味着打破向后兼容性; 安全性优先于兼容性保证。</p>
</div>
<div class="section" id="s-apis-marked-as-internal">
<span id="apis-marked-as-internal"></span><h3>标记为内部的 API<a class="headerlink" href="#apis-marked-as-internal" title="永久链接至标题">¶</a></h3>
<p>某些API在几种方式中被明确标记为 &quot;内部&quot; :</p>
<ul class="simple">
<li>一些文档提及了这些 API 并标为“内部”，如果确实如此，我们保留修改它的权利。</li>
<li>一些函数，方法以及其他对象以下划线“_”开头，这是 Python 声明其为“私有”的标准方式，如果一个方法以单下划线“_”开头，那么这意味着它是 Django 内部的一个 API。</li>
</ul>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">API 的稳定性</a><ul>
<li><a class="reference internal" href="#what-stable-means">什么是“稳定”？</a></li>
<li><a class="reference internal" href="#stable-apis">稳定的 API</a></li>
<li><a class="reference internal" href="#exceptions">例外</a><ul>
<li><a class="reference internal" href="#security-fixes">安全修复</a></li>
<li><a class="reference internal" href="#apis-marked-as-internal">标记为内部的 API</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>上一个主题</h4>
  <p class="topless"><a href="index.html"
                        title="上一章">元文件和杂记</a></p>
  <h4>下一个主题</h4>
  <p class="topless"><a href="design-philosophies.html"
                        title="下一章">设计理念</a></p>
  <div role="note" aria-label="source link">
    <h3>本页</h3>
    <ul class="this-page-menu">
      <li><a href="../_sources/misc/api-stability.txt"
            rel="nofollow">显示源代码</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>快速搜索</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="转向" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">7月 23, 2021</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="index.html" title="元文件和杂记">previous</a>
     |
    <a href="index.html" title="元文件和杂记" accesskey="U">up</a>
   |
    <a href="design-philosophies.html" title="设计理念">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>